.so ../bk-macros
.TH "bk tag" "\*[BKVER]" %E% "\*(BC" "\*(UM"
.\"    ====================== BitKeeper tags ======================
.SH NAME
bk tag \- tag the \*(BK repository with a symbolic name
.br
bk tags \- list tagged changesets
.SH SYNOPSIS
.B bk tag
.[OPTreq] \-r rev
.ARG symbol
.br
.B bk tags
.[ARG] repo
.SH DESCRIPTION
.LP
Tags (aka symbols or labels) are used when you want to record the state of 
a tree.  It is quite common to \*(lqtag the tree\*(rq with a release name when 
shipping a product to customers.  
.LP
To add a tag to the repository, make sure that you've checked everything
in and created a changeset.  You can use bk status to see what needs to
be checked in and/or committed to a changeset. Tag the tree by typing:
.DS
$ bk tag Alpha
.DE
The Alpha tag will be set on the most recent changeset.  Or you
can commit a changeset and tag the tree at the same time with the
.Q \-\-tag
option to commit:
.DS
$ bk commit \-\-tag=Alpha
.DE
To see all the tagged changesets run
.DS
$ bk tags
.DE
which is just an alias for 
.DS
$ bk changes -t
.DE
Optionally, you can pass
.B bk tags
a repository URL (see
.BR "bk help url" ).
.LP
If you want to recover the state of the world as of a tag, do this:
.DS
$ bk clone \-rAlpha source_repository Alpha
.DE
which will create a repository which has everything up to and including
the Alpha changeset.
.LP
If you discover that you should have tagged a changeset after more
changesets have been added to the repository, use the 
.Q \-r 
option to
select the proper changeset.  You can find out which revision to tag
by running 
.BR "bk\ changes" .
.LP
A frequent problem is that you tag a changeset with \*(lqDone\*(rq and then
discover you aren't done.  You may update the tag to the later changeset
by running the 
.DS
$ bk tag Done 
.DE
command again.  If there are multiple tags
with the same name, \*(BK takes the most recently applied tag (which
means you can move a tag backwards by specifying an older revision of
the cset file).
.SH LEGAL TAGS
Certain characters are not allowed in tags because they conflict with
other parts of the \*(BK revision, date, and/or range name spaces.
.PP
A valid tag has to obey the following rules:
.IP \[bu]
Tags can't start with the characters: '@', '=', '-', '+', or '.'.
.IP \[bu]
Tags can't start with a digit ('0' to '9').
.IP \[bu]
Tags can't contain any character with an ASCII value less than 040
(octal) or in the following list: '|', '?', '*', the DEL 
character
(\\177), '~', '^', ':', ';', '/', '!', '"', '\'', '$', '%', '&', '\\', '(', ')', '[', ']', '{', '}',
or '`'.
.IP \[bu]
Tags can't contain spaces (' ').
.IP \[bu]
Tags can't contain the sequences "..", ".,", ",.", or ",,".
.PP
In a nested repository, this release only allows tags on the product,
not any of its components; future releases may allow both.
.SH BUGS
.LP
Need a way of setting a tag in
.BR "bk citool" .
.SH "SEE ALSO"
.SA admin
.SA changes
.SA commit
.SA log
.\" help://tags
.\" help://label
.\" help://labels
.SH CATEGORY
.B Repository
